home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / lollipop.hqx / Lollipop Manual / out.tex < prev    next >
Text File  |  1992-11-18  |  16KB  |  419 lines
  1. % Out.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter[chap:output] output
  4.  
  5. Every page is formatted according to a `page grid' consisting of
  6. three elements:
  7.  
  8. \Enumerate \item the page head, this is everything that's over the
  9. running text;
  10. \item the page foot, this is everything that is below the running
  11. text;
  12. \item the running text. \TeX\ acts as if text is on a long scroll,
  13. and the running text part of a page is simply a portion cut off from
  14. this scroll.\>
  15. Either or both of the head and foot of the page can be empty, but
  16. usually one of the two contains a page number.
  17.  
  18. \OutExample
  19. \OptionsMacro:ManPageSize=raggedbottom:10pt topskip:12pt
  20.  height:page=3cm width:page=5cm Stop
  21. \DefinePageGrid:TestPage macro:ManPageSize
  22.  pagerule textband:start text textband:stop
  23.  pagerule band:start PageCounter band:stop Stop
  24. \TestPage 
  25. This page does not contain much special.\EjectPage
  26. This page is hardly better.
  27. \OutExampleStop
  28.  
  29. This example illustrates how you first define a page grid by
  30. \refcs{DefinePageGrid}, and then activate it by calling its name. That
  31. last action is in fact not necessary: each definition of a page grid
  32. automatically installs that grid as the current one.
  33.  
  34. \Section Page dimensions
  35.  
  36. Most of the time it is easiest to specify the total height of a page,
  37. that is, including head and bottom, but sometimes it is more
  38. convenient to specify the height of the text, and let the head and
  39. foot simply go over and under that.
  40.  
  41. In the first case you can give the command \refcs{Height} with
  42. two parameters:
  43. \Ver>\Height:Page=23.5cm<Rev or inside a page grid definition the
  44. option \refopt{height}\n{:page=...}.
  45.  
  46. In the second case you can give the command
  47. \Ver>\Height:Text=19.55cm<Rev or inside a page grid definition the
  48. option \opt{height:text=...}.
  49.  
  50. In page grid definitions there is the additional option
  51. \opt{height:lines=23}.
  52.  
  53. The \cs{Height} command cannot be used in a page grid definition.
  54.  
  55. \Section Positioning the page on the paper
  56.  
  57. If your printer driver is up to specs (and you have not done any
  58. creative macro writing) it should have the upper left corner of the
  59. text landing at $2.54$cm from the top and left side of the paper.
  60. If the result is not to your liking, you can shift the page by
  61. \Ver>\Distance:hoffset= ...
  62. \Distance:voffset= ...<Rev
  63. These offset parameters are zero ordinarily, and they indicate the
  64. extra shift added to the customary $2.54$cm in horizontal and
  65. vertical direction.
  66.  
  67. \Section Page head, foot, text
  68.  
  69. Somewhere in the page grid the option \refopt{text} has to appear. This
  70. option has to be inside a \refopt{textband}:
  71. \Ver>    textband:start text textband:stop<Rev
  72. This is not a case of overspecification, because inside a textband
  73. the text option can appear more than once. In this manner a multicolumn
  74. page grid can be specified.
  75.  
  76. \def\sometext{Just a bit of words, words. }
  77. \edef\sometext{\sometext\sometext\sometext}
  78. \edef\sometext{\sometext\sometext\sometext\sometext}
  79. \OutExample
  80. \DefinePageGrid:TestPage macro:ManPageSize
  81.  pagerule textband:start text hwhite:3mm text textband:stop
  82.  pagerule band:start PageCounter band:stop Stop
  83. \FlushRight:no \sometext
  84. \OutExampleStop
  85.  
  86. Next to the option \opt{textband} there is \refopt{band}.
  87. Both are ways of
  88. creating a page wide band. The option \opt{band} is used for all
  89. material that is not a text column, for instance footers, as in the
  90. above examples.
  91.  
  92. The option \opt{band} can have one unusual parameter: \n{invisible}.
  93. This makes the band act as if it has zero height or width, depending
  94. on whether it is below or above the text, respectively.
  95.  
  96. \OutExample
  97. \DefinePageGrid:TestPage macro:ManPageSize
  98.  pagerule textband:start text hwhite:3mm text textband:stop
  99.  pagerule 
  100.  band:invisible block:start Style:bold PageCounter Spaces:2
  101.      stickout:left band:stop Stop
  102. \FlushRight:no \sometext
  103. \OutExampleStop
  104.  
  105. \SubSection More about text bands
  106.  
  107. The text band is that part of the page that has the text in it. You can
  108. also put other material in it, such as rules or white space.
  109.  
  110. \OutExample 
  111. \DefinePageGrid:TestPage macro:ManPageSize pagerule 
  112.  textband:start vrule white:3pt text white:3pt vrule textband:stop 
  113.  pagerule band:start white:fillup PageCounter band:stop Stop
  114. \TestPage This page contains some text, a bit more text,
  115. and even more than that. In all still just a few lines.\EjectPage
  116. This page contains more text, still more text, and still more. 
  117. \OutExampleStop
  118.  
  119. In the previous example the width of the page was specified.
  120. If we only give the width of the text, the page width is calculated
  121. dynamically. 
  122.  
  123. \OutExample 
  124. \DefinePageGrid:TestPage macro:ManPageSize
  125.  textband:start vrule white:3pt text white:3pt vrule textband:stop
  126.  pagerule band:start white:fillup PageCounter band:stop Stop
  127. \noindent This page contains some text, a bit more text,
  128. and even more than that. In all still just a few lines.\EjectPage
  129. This page contains more text, still more text, and still more. 
  130. \OutExampleStop
  131.  
  132. Note how the \refopt{pagerule} and \opt{band} objects stretch
  133. with the page.
  134.  
  135.  
  136. \SubSection Topskip
  137.  
  138. In between the page head and the text is some white space, the
  139. topskip, with special properties. The topskip is defined from the
  140. bottom of the head to the bottom of the first line of the text. If
  141. the height of this first line varies from page to page the topskip
  142. acts as a buffer, keeping the bottom-to-bottom distance constant.
  143.  
  144. Topskip is set by the option \refopt{topskip}, for example
  145. \Ver>    topskip:25pt<Rev
  146. but if this option is left out, the page grid uses the value of
  147. \cs{topskip} that was current at the time of the definition.
  148. Unfortunately there is no way to change this value after the definition.
  149.  
  150. \Section The page number
  151.  
  152. The page number behaves as if it had been defined by
  153. \Ver>\NewCounter:Page
  154. \CounterRepresentation:Page=1<Rev
  155. Thus you can use any command from section~\ref[sec:counters] on it.
  156. For instance, you can have page numbers in roman numerals by 
  157. specifying
  158. \Ver>\CounterRepresentation:Page=I<Rev
  159.  
  160. The page number is typically used as the option \refopt{PageCounter},
  161. but for some applications the corresponding command \refcs{PageCounter}
  162. can be used.
  163.  
  164. \Section[sec:page:tests] Page tests
  165.  
  166. The page grid definition can set/query several properties of the
  167. page. The following tests have been provided (see
  168. section~\ref[sec:tests] for tests):
  169. \Ver>\DefineTest:IsRightPage
  170. \DefineTest:IsLeftPage
  171. \DefineTest:FirstPage
  172. \DefineTest:LastPage
  173. \DefineTest:FlushBottom<Rev
  174. \Itemize\item The tests for left/right pages are done by
  175.  testing whether the page number of odd or even.
  176. \item The first/last page tests can be used either for the whole
  177. document, or for a file that's loaded as an \cs{InputFile}.
  178. \item The first page test doesn't work at present.
  179. \>
  180.  
  181. \OutExample
  182. \DefinePageGrid:TestPage macro:ManPageSize
  183.  pagerule textband:start text textband:stop pagerule
  184.  band:start ifIsLeftPage else hwhite:fillup fi PageCounter 
  185.      band:stop Stop 
  186. This is a left hand page. \EjectPage 
  187. This page is on the right side of a spread. 
  188. \OutExampleStop
  189.  
  190. \Section Running heads / footers
  191.  
  192. Above it was explained how pages can be given a head and foot part.
  193. Quite often you want changing information in such parts, for instance
  194. the head of a left page often contains the number or title of section
  195. that was current when that page started; the head of a right page
  196. often contains the number or title of the section that was current
  197. when that page ended.
  198.  
  199. In \Lollipop\ all constructs that have a title or a counter can have
  200. that information referenced in page grids.
  201. \Description\item \refcs{FirstPlaced}:SectionTitle
  202. Take the title of the first section that started on this page, or
  203. the last one that started before this page if no section started on
  204. this page.\item \refcs{LastPlaced}:SubSectionCounter
  205. Take the title of the last subsection that started on this page, or
  206. the last one that started before this page if no subsection started
  207. on this pgae.\item \refcs{PreviousPlaced}:SectionCounter
  208. Take the counter value of the last section that started before this
  209. page.\>
  210.  
  211. \OutExample
  212. \DefinePageGrid:TestPage macro:ManPageSize
  213.  pagerule textband:start text textband:stop pagerule 
  214.  band:start Style:italic FirstPlaced:HeadTitle
  215.             white:fillup PageCounter band:stop Stop
  216. \DefineHeading:TestHeading Style:bold 
  217.  line:start TestHeadingCounter Spaces:2 title line:stop Stop
  218. \TestHeading A first section\par And some text.\EjectPage
  219. This page contains text. \TestHeading A second Section\par
  220. And more text.
  221. \OutExampleStop
  222.  
  223. The commands \cs{FirstPlaced} and \cs{PreviousPlaced} are typically
  224. used on left pages; \cs{LastPlaced} is more common on right pages.
  225. You can test on what sort of page you are; see
  226. section~\ref[sec:page:tests].
  227.  
  228. \OutExample
  229. \DefinePageGrid:TestPage macro:ManPageSize
  230.  pagerule textband:start text textband:stop pagerule 
  231.  band:start Style:italic 
  232.      ifIsLeftPage FirstPlaced:HeadTitle white:fillup fi
  233.      PageCounter
  234.      ifIsRightPage white:fillup LastPlaced:HeadTitle fi
  235.      band:stop Stop
  236. \DefineHeading:TestHeading Style:bold 
  237.  line:start TestHeadingCounter Spaces:2 title line:stop Stop
  238. \TestHeading A first section\par And some text.
  239. \TestHeading Second section\par More text.\EjectPage
  240. \TestHeading Third section\par Is on the right page.
  241. \TestHeading Fourth section\par Concludes this page.
  242. \OutExampleStop
  243.  
  244. \ImpNote 
  245.  
  246. \iSection Marks
  247.  
  248. All constructs that can have marks add their mark
  249. items to a globally maintained list:
  250. \Ver>\newtoks\mark@items<Rev
  251.  
  252. Only headings and page grids can have marks. Hence by default
  253. mark generation is switched off.
  254. \Ver>\newif\ifhas@marks
  255. \add@generic@default{\has@marksno}<Rev
  256.  
  257. At the moment all counters and titles wind up in the mark structure:
  258. \Ver>\def\install@counter#1{ ...
  259.     \xp\add@mark@item\xp{\@name Counter} ... }
  260. \add@generic@stop@default
  261.    {\ifhas@title\xp\add@mark@item\xp{\@name Title}\fi}<Rev
  262.  
  263. The test whether the object currently being defined has marks
  264. is performed by \cs{add@mark@item}:
  265. \Ver>\def\add@mark@item#1{\ifhas@marks
  266.     \csarg\newtoks{mark@toks@#1}%
  267.     \Tmessage[mark]{Adding mark item #1}%
  268.     \global\mark@items\xp{\the\mark@items{#1}}\fi}<Rev
  269.  
  270. This routine allocates a token list per mark item. For instance,
  271. for a \cs{SectionTitle} a \cs{mark@toks@SectionTitle} will be allocated.
  272. Every time a \cs{Section} occurs, a call
  273. \Ver>\refresh@mark@item{SectionTitle}{the title}<Rev
  274. will then be made. This merely refreshes the contents of the
  275. specific token list:
  276. \Ver>\def\refresh@mark@item#1#2%
  277.    {\csarg\global{mark@toks@#1}{#2}}<Rev
  278.  
  279. Also, a call to \cs{place@mark} will be made, which puts a mark
  280. on the current page, containing a list of item name~/ item value
  281. pairs. This proceeds fully by expansion.
  282. \Ver>\def\get@mark@items#1{\if\EqualStringX{#1}{SM}%
  283.     \else{#1}{\csarg\the{mark@toks@#1}}%
  284.          \xp\get@mark@items
  285.     \fi}
  286. \def\place@mark
  287.    {\mark{\xp\get@mark@items\the\mark@items{SM}}}<Rev
  288.  
  289. Retrieving information out of a mark consists of traversing the list
  290. of pairs, and taking the value of the keyword requested.
  291. Thus you can call \cs{FirstPlaced:SectionTitle}.
  292. \Ver>\def\FirstPlaced:#1 
  293.    {\Tmessage[mark]{First Placed #1 from \firstmark}%
  294.     \xp\get@placed\xp{\firstmark}{#1}}<Rev
  295. The \cs{PreviousPlaced} and \cs{LastPlaced} commands are analogous,
  296. but based on the \cs{topmark} and \cs{botmark}.
  297.  
  298. Again, everything here proceeds by expansion only, so the
  299. string tester will consume some processor power.
  300. \Ver>\def\get@placed#1#2{\get@@placed{#2}#1{SM}{}$}% SM: StopMarker
  301. \def\get@@placed#1#2#3{\if\EqualStringX{#2}{SM}%
  302.          \xp\take@to@dollar
  303.     \else\if\EqualStringX{#1}{#2}%
  304.               \maybe@uppercase{#3}%
  305.               \xp\xp\xp\take@to@dollar
  306.          \else\xp\xp\xp\get@@placed\fi
  307.     \fi{#1}}<Rev
  308.  
  309. \ImpNoteStop
  310.  
  311. \Section Alternating page grids
  312.  
  313. In \Lollipop\ it is very easy to switch page grids: you simply specify
  314. \Ver>    NextPageGrid:otherpage<Rev as one of the options in the
  315. definition. If no next grid is indicated, the same page grid keeps
  316. being used continuously until another page grid is activated
  317. explicitly.
  318.  
  319. \OutExample
  320. \DefinePageGrid:LTestPage macro:ManPageSize
  321.  pagerule textband:start text textband:stop pagerule 
  322.  band:start Style:italic 
  323.      FirstPlaced:HeadTitle white:fillup PageCounter 
  324.      band:stop NextPageGrid:RTestPage Stop
  325. \DefinePageGrid:RTestPage macro:ManPageSize
  326.  pagerule textband:start text textband:stop pagerule 
  327.  band:start Style:italic 
  328.      PageCounter white:fillup LastPlaced:HeadTitle
  329.      band:stop NextPageGrid:LTestPage Stop
  330. \DefineHeading:TestHeading Style:bold 
  331.  line:start TestHeadingCounter Spaces:2 title line:stop Stop
  332. \LTestPage
  333. \TestHeading A first section\par And some text.
  334. \TestHeading Second section\par More text.\EjectPage
  335. \TestHeading Third section\par Is on the right page.
  336. \TestHeading Fourth section\par Concludes this page.
  337. \OutExampleStop
  338.  
  339. Another very useful application of this mechanism is to have a
  340. special definition for the opening page of a chapter. This manual uses a
  341. one-shot page grid \cs{EmptyPage} to remove the header and footer on the
  342. title page. It installs \cs{LeftPage} as the next grid.
  343.  
  344. \Section Additional User Control
  345.  
  346. \SubSection Elementary manipulation
  347.  
  348. There are a few commands for simple page manipulation:
  349. \Description\item \refcs{EjectPage}
  350. The current page is filled up with white space, and
  351. a new page is started.\item \refcs{ToRecto}
  352. As \cs{EjectPage} but if the next page is a left page (meaning
  353. that the page number is even) then the page number is increased by
  354. one, so that the next page is a right hand page.\item \refcs{ToVerso}
  355. As \cs{ToRecto}, except that the next page is a left page.
  356. \>
  357.  
  358. Additionally, \refcs{NoPages} lets
  359. all formatting and updating of values be performed, but
  360. no pages are written to the dvi file;
  361. \refcs{PagesOut}
  362. reverts the effect of previous command. Note that \cs{NoPages} does not
  363. incur any savings in time: full processing of the document is performed.
  364.  
  365. \ImpNote
  366.  The test \cs{ifsink@pages} determines whether pages will be output
  367. to the dvi file (if the test is false) or silently dropped (if true).
  368. The sheet counter is only updated for pages written to the dvi file
  369. so that it will takes consecutive values no matter if pages are sunk.
  370. If a pages is dropped, \cs{deadcycles} is set to zero, otherwise it would
  371. not be possible to drop more than \cs{maxdeadcycles} pages.
  372. \ImpNoteStop
  373.  
  374. When a page is finished, the whole box is given to
  375. \refcs{CurrentShipout}, which is by default \cs{shipout}. However, you
  376. are free to define it otherwise. If your
  377. \cs{CurrentShipout} does not actually ship out pages, you may want to
  378. set \refcs{CountSheetsno} to prevent the effective page counter from
  379. being updated.
  380.  
  381. Redefining \cs{CurrentShipout} usually goes together with
  382. \refcs{SuspendOutput} and \refcs{ResumeOutput}. These commands
  383. temporarily save the page number and the current state of the page.
  384. See the definition of
  385. \cs{OutputExample} in the appendix of this manual for an example. 
  386.  
  387. If you want to see te output routines in action, specify
  388. \Ver>\Trace:out<Rev In addition \Ver>\Trace:mark<Rev tells you what
  389. information is being saved for running head and foot lines.
  390.  
  391. \endinput
  392.  
  393. \ImpNote 
  394.  
  395. \iSection Initial setup of output routines
  396.  
  397. \Ver>
  398.     \csarg\edef{\@command}{%
  399.           \nxp\EjectPage
  400.           \nxp\install@output@routine{\@name}%
  401.           \global\hsize= \ifseen@text \CSname{\@name @text@width}%
  402.                      \else \CSname{\next@page@grid @text@width}%
  403.                      \fi
  404.           \outer@start@commands \after@indent
  405.           }<Rev
  406.  
  407. \Ver>
  408. \def\install@output@routine#1{{\globaldefs\@ne
  409.     \output=\xp{\csname#1@routine\endcsname}%
  410.     \def\output@routine{#1}%
  411.     \Tmessage[out]{Install output: #1 ---}%
  412.     \@pagegrid@installedyes
  413.     \csname#1@install@parameters\endcsname
  414.     \edef\Next@PageGrid
  415.         {\nxp\install@output@routine{\csname#1@Next@PageGrid\endcsname}}%
  416.     }}<Rev
  417.  
  418.  
  419. \ImpNoteStop